feat!: per-account reconcile report and fleet reconcile for reporting subscriptions - #1802

Summary

TS parity for the buyer reconcile() report (decisions 1 and 2 of the reporting-subscriptions DX follow-ups).

Per-account report. ReconcileReport.accounts now holds one ReconcileAccount per account, the shape of TS ReconcileAccount (adcp-client#3576, #3581):

ReconcileAccount(
    account_id="acc_a",
    subscription_ids=("analytics-hourly",),
    status="reconciled" | "unauthorized" | "failed",
    unauthorized_at="2026-11-01T02:05:00Z",   # unauthorized only
    withheld_period_count=3,                  # unauthorized only, the seller's count
    error=ReconcileAccountError(task="get_reporting_status", code="TASK_FAILED", message=...),  # failed only
)

• failed records the first read that failed for the account: get_media_buys, get_reporting_status, or coverage (a CoverageInputError, with its code). Paging that does not finish is LIMIT_EXCEEDED.
• A principal or roster failure is the entry account_id="*", as in TS.
• to_dict() serves the objects under accounts. The report also carries agent_id and since, as TS does.
• Old shape: report.account_ids is the tuple of ids accounts used to be. It leaves out "*". The events module now reads it.

Fleet fan-out. ADCPMultiAgentClient.reporting is a FleetReportingClient:

fleet = await multi.reporting.reconcile(since="2026-11-01", concurrency=4, agent_ids=None)
fleet.by_seller   # agent_id -> ReconcileReport
fleet.issues      # FleetReconcileIssue(agent_id, code, message, ...)
fleet.definitive  # every seller definitive and none failed
fleet.summary     # summed ReconcileSummary

• Each seller is read through its own multi.agent(id).reporting, so the per-seller cache of last-read facts carries across runs.
• The report key is issues, as in TS's fleet report after #3581.
• A seller whose principal could not be read, or whose run raised, becomes a SUBSCRIPTION_PRINCIPAL_UNAVAILABLE fleet issue with its agent_id. It is left out of by_seller and the summary. In TS, that read throws inside the fleet. Python's single-seller reconcile() turns it into a report issue instead, so the fleet lifts it.
• One difference from TS: an unknown agent_ids entry is refused before dispatch (ReportingSubscriptionError, INVALID_REQUEST, dispatched=False). TS filters it out silently. So is concurrency < 1, as in TS.

Outcome names (decision 3). No change needed: Python's accounts.change outcomes already use kind="separate_account" and kind="matched_existing" (AccountSeparate, AccountMatched), the names TS #3587 adopted.

Docs: the buyer guide gains the account statuses and an Across sellers section. The errors guide covers failed entries and fleet issues, and the README shows the fleet call.

Test plan

• tests/test_reporting_subscription_reconcile.py:
  • reconciled entry and to_dict;
  • "*" on roster and principal failures;
  • a ledger failure is failed with get_reporting_status;
  • a lost account is unauthorized with unauthorized_at, withheld_period_count and subscription_ids;
  • fleet: two healthy sellers and one with no principal, the summed summary, agent_ids, refusals, and multi.reporting delegating to each agent's reporting.
• Events, receipts, TS-parity, public API and export-surface suites.
• ruff check, ruff format --check, mypy on the changed modules.

BREAKING CHANGE: ReconcileReport.accounts is a tuple of ReconcileAccount instead of account-id strings, and to_dict() serves objects under accounts. Read report.account_ids for the ids.

🤖 Generated with Claude Code